/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.platformservice.persistence.api;

import org.proteusframework.core.api.model.IDescriptor;
import org.proteusframework.core.api.model.INamespace;
import org.proteusframework.core.base.Namespace;

import java.util.List;
import java.util.Map;
import java.util.Properties;

/**
 * Read-only representation of a project. Manipulation of a project descriptor must occur through the primordial
 * <code>IPersistenceService</code> to ensure proper property change listener notification.
 */
public interface IProjectDescriptor extends INamespace, IDescriptor
{
    String FAMILY = "org.proteusframework.platformservice";

    String ID = "Empty";

    INamespace EMPTY_PROJECT_DESCRIPTOR_NS = new Namespace(FAMILY, ID, "Empty project descriptor");

    /**
     * Updates the current project description.
     *
     * @param description New project description; may be null
     */
    void setDescription(String description);

    /**
     * Unmodifiable map of the property groups and their nested Properties map.
     *
     * @return Unmodifiable map
     */
    Map<String, Properties> getPropertiesMap();

    /**
     * Unmodifiable list of property groups.
     *
     * @return Unmodifiable list of property groups
     */
    List<String> listPropertyGroups();

    /**
     * Unmodifiable list of property group keys for the given property group.
     *
     * @param propertyGroup Property group
     * @return Unmodifiable list of property keys under the specified property group
     */
    List<String> listPropertyGroupKeys(String propertyGroup);

    /**
     * Unmodifiable set of properties associated with the given group. Any modifications will not cascade into the
     * actual project descriptor.
     *
     * @param propertyGroup Property group to lookup
     * @return Unmodifiable set of properties
     */
    Properties getProperties(String propertyGroup);

    /**
     * Determines if the given key exists within the given property group.
     *
     * @param propertyGroup Property group
     * @param key           Property key
     * @return true, if the property is defined
     */
    boolean hasProperty(String propertyGroup, String key);

    /**
     * Gets the value of the property key under the specified property group.
     *
     * @param propertyGroup Property group
     * @param key           Property key
     * @return value if present, or null otherwise
     */
    String getProperty(String propertyGroup, String key);
}
